/*
 *  Copyright 2008 Martin Fryč (martin@fryc.eu).
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 * 
 *       http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *  under the License.
 */
package eu.fryc.martin.micromq.storage;

import javax.jms.Destination;
import javax.jms.InvalidDestinationException;
import javax.jms.JMSException;
import javax.jms.Message;

/**
 * MicroMQ storage engine manager.
 * 
 * @author mfryc
 */
public interface MicroMQStorage {

	/**
	 * Create new destination.
	 * 
	 * @param destination
	 *            destination
	 * 
	 * @throws javax.jms.JMSException
	 *             if destination creation fail
	 */
	public void createDestination(Destination destination) throws JMSException;

	/**
	 * Delete existing destination. This destination could not contain any
	 * messages.
	 * 
	 * @param destination
	 *            destination
	 * 
	 * @throws javax.jms.JMSException
	 *             if destination delete fail
	 * @throws javax.jms.InvalidDestinationException
	 *             if no such destination exists
	 */
	public void deleteDestination(Destination destination) throws JMSException, InvalidDestinationException;

	/**
	 * Put new message into destination.
	 * 
	 * @param connectionId
	 *            connection id
	 * @param message
	 *            message
	 * 
	 * @throws javax.jms.JMSException
	 *             if put fail
	 * @throws javax.jms.InvalidDestinationException
	 *             if no such destination exists
	 */
	public void put(String connectionId, Message message) throws JMSException, InvalidDestinationException;

	/**
	 * Get message from destination.
	 * 
	 * @param destination
	 *            destination
	 * @param connectionId
	 *            connection id
	 * @param timeout
	 *            timeout of get method (0 - no wait, negative - infinite wait,
	 *            other - milis wait time)
	 * 
	 * @return message or null if timeout occurs and destination does not
	 *         contain any message
	 * 
	 * @throws javax.jms.JMSException
	 *             if get fail
	 * @throws javax.jms.InvalidDestinationException
	 *             if no such destination exists
	 */
	public Message get(Destination destination, String connectionId, long timeout) throws JMSException,
			InvalidDestinationException;

	/**
	 * Commit messages included in transaction. Behaviour of thid method depends
	 * on session configuration.
	 * 
	 * @param connectionId
	 *            connection id
	 * 
	 * @throws javax.jms.JMSException
	 *             if commit fail
	 */
	public void commit(String connectionId) throws JMSException;

	/**
	 * Rollback messages included in this transaction. Behaviour of thid method
	 * depends on session configuration.
	 * 
	 * @param connectionId
	 *            connection id
	 * 
	 * @throws javax.jms.JMSException
	 *             if commit fail
	 */
	public void rollback(String connectionId) throws JMSException;

}
